H5 Games Ads topic

Before you start

This package is only intended for use by web games.

Please apply to the beta using this form. Once approved, you may use the package.

Without approval, your code may not behave as expected, and your AdSense account may face policy issues.

H5 Games Ads

The h5.dart library provides a way to use the AdSense Ad Placement API to display ads in games on the web.

H5 Games Ads offers high-performing formats:

  • Interstitials: Full-screen ads that are displayed at natural breaks in your game, such as between levels. Users can choose to either click these ads or return to your game.
  • Rewarded ads: Ads that users can choose to interact with in exchange for in-game rewards.

H5 Games Ads formats support display ads, TrueView and Bumper video ads.

Review the Policy for ad units that offer rewards before using Rewarded Ads.

Usage

First, initialize AdSense (see the Initialization topic).

Import the H5 Games Ads client

import 'package:google_adsense/h5.dart';

This provides an h5GamesAds object with two methods: adBreak to request ads, and adConfig to configure the ads that are going to be served.

Displaying an Interstitial Ad

To display an Interstitial Ad, call the adBreak method with an AdBreakPlacement.interstitial:

h5GamesAds.adBreak(
  AdBreakPlacement.interstitial(
    type: BreakType.browse,
    name: 'test-interstitial-ad',
    adBreakDone: _interstitialBreakDone,
  ),
);

Ad break types

The following break types are available for interstitial ads:

BreakType Description
start Before the app flow starts (after UI has rendered)
pause Shown while the app is paused (games)
next Ad shown when user is navigating to the next screen
browse Shown while the user explores options

See the Ad Placement API reference on Interstitials for a full explanation of all the available parameters.

Displaying a Rewarded Ad

Review the Policy for ad units that offer rewards before using Rewarded Ads.

To display a Rewarded Ad, call the adBreak method with an AdBreakPlacement.rewarded:

h5GamesAds.adBreak(
  AdBreakPlacement.rewarded(
    name: 'test-rewarded-ad',
    beforeReward: _beforeReward,
    adViewed: _adViewed,
    adDismissed: _adDismissed,
    afterAd: _afterAd,
    adBreakDone: _rewardedBreakDone,
  ),
);

If a Rewarded ad is available, the beforeReward callback will be called with a showAdFn function that you can call to show the Ad when the player wants to claim a reward.

When the user fully watches the ad, the adViewed callback will be called, and the reward should be granted.

If the user dismisses the ad before they're eligible for a reward, the adDismissed callback will be called instead.

See the Ad Placement API reference on Rewarded ads for a full explanation of all the available parameters, and the call sequence for a rewarded ad.

The adBreakDone callback

Note that a call to adBreak might not show an ad at all. It simply declares a place where an ad could be shown.

If the API does not have an ad to show it will not call the various before/after callbacks that are configured. However, if you provide an adBreakDone callback, this will always be called, even if an ad is not shown. This allows you to perform any additional work needed for the placement, such as logging analytics.

The adBreakDone function takes as argument an AdBreakDonePlacementInfo object, which contains a breakStatus property. See the BreakStatus enum docs for more information about the possible values.

Configuring Ads

The adConfig function communicates the game's current configuration to the Ad Placement API. It is used to tune the way it preloads ads and to filter the kinds of ads it requests so they're suitable.

You can call adConfig with an AdConfigParameters object at any time, like this:

h5GamesAds.adConfig(
  AdConfigParameters(
    // Configure whether or not your game is playing sounds or muted.
    sound: SoundEnabled.on,
    // Set to `on` so there's an Ad immediately preloaded.
    preloadAdBreaks: PreloadAdBreaks.on,
    onReady: _onH5Ready,
  ),
);

See the Ad Placement API reference on adConfig for a full explanation of all the available parameters.

Libraries

h5 H5 Games Ads